Tracking a Project in GitHub

Track the whole workspace/ directory as a Git repository when you want to recreate your setup. It contains individual projects and global_data, which applies to every project. A repository containing only one project cannot carry shared client profiles, engine defaults, or global notification preferences.

Find the workspace

A downloaded engine package uses this layout:

DARTWIC/
  engine/
    bin/                         # installed engine binaries
    config.json                  # workspace location, credentials, local overrides
    rapid/my-project/            # recordings, exports, channel_state.json
    argus/my-project/            # events, responses, sessions, database sidecars
    dcode/my-project/            # generated native compiler cache
    share/my-project/            # local Share secret values
    projects/my-project/         # local association between checkout and history
  workspace/                     # initialize or clone Git HERE
    .gitignore
    .gitattributes
    global_data/
      engine_config.json         # shared engine defaults and selected project
      rapid_config.json          # shared recording settings
      client_info.json           # remembered client profiles
      notification_mutes.json    # global mute choices
      schematic_nodes/           # shared authored definitions
      plugin_icons/
    my-project/
      project.json               # stable identity and dependencies
      edge_node_connections.json # endpoints, transport settings, secret references
      notification_mutes.json    # optional project mute choices
      scripts/
      rapid/channel_snapshot.json
      rapid/recording_config.json # optional complete project recording policy
      schematics/
      schematic_nodes/
      modules/
      tasks/
      checklists/

engine/config.json selects the workspace with "workspace_root_directory": "../workspace". Development instances may use "./workspace"; absolute paths also work. Relative paths resolve from the directory containing config.json.

What belongs in Git?

Keep rapid/channel_snapshot.json in Git. Periodic saves still run about every 60 seconds by default and at shutdown. Configuration edits can update it. Unchanged configuration leaves its contents and modification time unchanged. Live values, timestamps, and runtime provenance go into engine/rapid/<project>/channel_state.json.

On a fresh engine, explicit startup values take precedence. Dynamic channels without explicit startup values begin at zero if there is no local state. Fixed channels are reconstructed from scripts, tasks, or plugins; their startup settings travel in the snapshot.

Recordings, Argus databases/WALs, compiler caches, exports, updater files, and live connection state stay under engine/. Installed plugins are dependencies: record their IDs/versions and install them on the receiving engine.

Credentials and local overrides

The workspace describes the setup; secret values are supplied locally. Engine passwords and licensing credentials stay in engine/config.json or their licensing files. Share passwords, tokens, private keys, and credential objects stay in engine/share/<project>/connections.json.

Share connection saves retain ordinary plugin fields in the project. Recognized secret fields are replaced with null placeholders and listed in secret_fields as JSON pointers, such as /password or /custom/api_key. Plugins with differently named credentials must declare those paths in secret_fields, or group them under secrets. The engine does not guess every possible secret name: review plugin configuration before committing.

A cloned node retains its address and sharing policy even when credentials are missing. Supply them through the connection configuration UI/API before reconnecting. A transport with no secret requirements can retain its configuration without a local settings file.

Use overrides in the local engine/config.json when the receiving computer needs a different address, port, node name, or capacity:

{
  "workspace_root_directory": "../workspace",
  "server_admin_password": "SET-LOCALLY",
  "license_key": "",
  "overrides": {
    "node_name": "SECONDARY_ENGINE",
    "server_port": 7100
  }
}

Local overrides take precedence without rewriting shared defaults. active_project_name belongs in global_data/engine_config.json and cannot be overridden locally. Changes through the engine’s project selector persist that choice in the workspace.

Publish to GitHub

1. Save authored files and stop the engine so configuration has finished writing.

2. Open a terminal inside the configured workspace container, not inside engine/ or an individual project.

3. Initialize Git and review the staged content:

   git init -b main
   git add .
   git diff --cached --stat
   git diff --cached
   git commit -m "Add DARTWIC workspace"

4. Create an empty GitHub repository and push using your normal GitHub authentication:

   git remote add origin https://github.com/YOUR-ACCOUNT/YOUR-WORKSPACE.git
   git push -u origin main

The engine scaffolds workspace and project Git exclusions and LF text attributes. Never ignore every rapid/ directory: that would hide channel configuration. Review configuration for credentials and machine paths before committing; an exclusion cannot remove content already committed.

For subsequent updates, stop the engine before pulling or editing persisted configuration externally. Restart after pulling. Recording samples or events, observing a mute, or reconnecting a known client should not create configuration changes. Deliberately changing client profiles, endpoints, mutes, or project selection should.

Run the workspace on another engine

1. Download and extract a compatible engine, leaving it stopped.

2. Clone into an empty directory. For example, from the package’s top level:

   git clone https://github.com/YOUR-ACCOUNT/YOUR-WORKSPACE.git my-workspace

3. Set "workspace_root_directory": "../my-workspace" in engine/config.json. This points to the cloned container holding global_data and the projects. There is no need to merge it into the package’s supplied workspace.

4. Supply local passwords/license settings and any required Share secrets. Install declared engine and interface plugins. Apply local overrides if this computer needs a different node name or port.

5. Start the engine. It uses the tracked active-project selection and shared defaults, remembers client profiles and Share endpoints, and applies global plus project mute choices. Live clients still need to connect; remembered profiles do not represent current sessions.

6. Run a representative task and inspect channels and events. Native scripts require the toolchain described in Native C++ Execution.

The receiving engine creates fresh recording and Argus history. Keep each project’s project_id unchanged when cloning it. Create a new project through the engine when you want a distinct identity rather than a clone.

Dependencies and portability checks

Each project’s project.json declares required engine plugins and project-relative resource files:

{
  "schema_version": 1,
  "project_id": "KEEP-THE-ID-GENERATED-FOR-YOUR-PROJECT",
  "plugins": [{ "id": "your_driver_plugin", "version": "1.0.0" }],
  "required_files": ["assets/process-diagram.svg"]
}

Plugin versions are exact; omit version to accept any installed version. The manifest does not install plugins. Document interface plugins, hardware, and any plugin-owned installation configuration in the workspace README.

The dartwic/projects/check-portability operation checks declared dependencies, project and global_data JSON resources for absolute paths and common credential fields, and remembered connections for missing local secrets. It also identifies native execution and checks for CMake on PATH. It does not execute a compiler, establish network/hardware reachability, or discover every dependency in arbitrary plugin code, scripts, or YAML.

Project schematic_nodes/ definitions take precedence over shared definitions with the same category and display name. A whole-workspace clone carries both. A single-project repository remains possible when its shared dependencies are deliberately supplied separately.

Mute scope, rename, and backup

Existing engine mute controls save choices in global_data/notification_mutes.json. The dartwic/notifications/set-muted operation also accepts "scope": "project" to save a choice in the active project. Global choices apply to all projects; project choices apply only to that project. If an ID is muted in both scopes, both must be unmuted; the notification center handles this. Mutes do not expire automatically or disappear when one occurrence is resolved.

Use the engine’s managed rename to keep the project and its RAPID, Argus, DCode, Share-secret, and ownership directories together. A manual folder rename does not rename recording storage. Ownership checks prevent an unrelated checkout from silently attaching to existing history under the same name.

Git backs up definitions and preferences. For a full history backup, stop the engine and also copy engine/rapid/<project>/ and engine/argus/<project>/, including sidecars. Back up local credentials securely if needed. Compiler caches can be regenerated.